The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v5 of the API first released as part of Metasys 13.0. This documentation was last updated on July 5, 2022, 6:03 PM (UTC).

This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.

This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.

The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 13.0, the supported versions are v2, v3, and v5.

Note: v1 is not supported by Metasys 13.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v5/spaces for version 5 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v5+json for version 5.

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

• Get an object
• Edit an object
• Get attribute value
• List the commands of an object
• Invoke a command
• Batch object operations

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

• All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
• Enumeration set names and set members are case sensitive (eg. reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

Payloads may contain links to related data, each represented as a property sharing the name of the respective relationship. The links point to either single or multiple related entities. A link to a single entity points to the canonical path for that entity. A link to multiple entities points to a path dedicated to representing that particular relationship.

For example, if object /objects/a has children /objects/b and /objects/c, the payload returned by /objects/a will have a property objects with a value of /objects/a/objects, because multiple children can be returned. However, the payload returned by /objects/b/ will contain a property parent with a value of /objects/a (not /objects/b/parent), because the relationship represents a single entity.

Additionally, each payload contain a self property, which contains a link representing the path used to obtain the data contained in the current payload.

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

Activities are a superset of all alarms and audits in a Metasys system. The activities operations provide the ability to view, annotate, and manage audits and alarms. The use of filters, sorting, and paging allow for the ability to narrow searches to find activities more efficiently.

Streaming Events

Clients can subscribe to streaming events for activities. To establish a subscription, provide a METASYS-SUBSCRIBE header with the Get Activities operation. The value of this header is the stream id you received when you opened a stream. The events received on a subscription are relevant to the filters of the original GET operation.

See also:

• Streaming
• Get a stream
• Stream keep alive

The following are types of events sent by an activities subscription along with example data payloads for each:

• activity.alarm.ack - Indicates a management status change of an alarm activity to acknowledged.

  Example Data Payload

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "acknowledged",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.annotate - Indicates the addition of an annotation to an alarm activity, providing the information for the annotated alarm.

  Example Data Payload

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.discard - Indicates a management status change of an alarm activity to discarded.

  Example Data Payload

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "discarded",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "Engine1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "acknowledgedTime": "2021-02-16T20:31:02Z",
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.alarm.new - Indicates the creation of an alarm activity.

  Example Data Payload

  {
    "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
    "activity": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
      "objectName": "OA_T",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T20:30:00Z",
      "spaces": [
        {
          "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
          "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
          "name": "Floor 1",
          "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "equipment": [
        {
          "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
          "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
          "equipmentName": "IDU1",
          "shortName": null,
          "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
        }
      ],
      "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
      "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
      "alarm": {
        "message": "",
        "alarmGeneratorObject": {
          "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
          "referencedObject": {
            "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
          }
        },
        "isAckRequired": true,
        "type": "alarmValueEnumSet.avHiAlarm",
        "priority": 70,
        "category": "objectCategoryEnumSet.generalCategory",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "triggerValue": {
          "item": "2.0",
          "schema": {
            "type": "string",
            "metasysType": "string",
            "units": {
              "id": "unitEnumSet.degF",
              "title": "deg F"
            }
          }
        },
        "description": ""
      }
    },
    "effectivePermission": {
      "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "canAcknowledge": true,
      "canDiscard": true,
      "canAnnotate": true
    }
  }
  

• activity.audit.new - Indicates the creation of an audit activity.

  Example Data Payload

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": null,
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

• activity.audit.annotate - Indicates the addition of an annotation to an audit activity, providing the information for the annotated audit.

  Example Data Payload

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "pending",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

• activity.audit.discard - Indicates a management status change of an audit activity to discarded.

  Example Data Payload

  {
    "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
    "activity": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "itemReference": "{hostname}:{deviceHostname}",
      "objectName": "MS-NAE5510-3",
      "activityManagementStatus": "discarded",
      "creationTime": "2021-02-16T16:21:10.23Z",
      "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
      "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
      "audit": {
        "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
        "status": null,
        "preData": null,
        "postData": {
          "item": "10.10.198.131",
          "schema": {
            "type": "string",
            "metasysType": "string"
          }
        },
        "parameters": [],
        "errorString": null,
        "user": "MetasysSysAgent",
        "signature": null,
        "classLevel": "auditClassesEnumSet.userActionAuditClass",
        "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
        "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
        "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
        "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
      }
    },
    "effectivePermission": {
      "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
      "canDiscard": true
    }
  }
  

• activity.heartbeat - Indicates the activities service is alive.

  Example Data Payload

  {
    "currentTime": "2021-02-16T16:21:10.23Z",
    "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
  }
  

Filter Behavior

Filters supplied to an activities request will limit the results to activities for which they apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change may impact the original set of activities you subscribed to. To illustrate, consider the following scenario:

• You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
• In this state, one of the activities in your original list is discarded by another user.

When this occurs, you will receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.